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Abstract 

RunMC is an object-oriented framework aimed to generate and to analyse high- 
energy coUisions of elementary particles using Monte Carlo simulations. This pack- 
age, being based on C++ adopted by CERN as the main programming language for 
the LHC experiments, provides a common interface to different Monte Carlo models 
using modern physics libraries. Physics calculations (projects) can easily be loaded 
and saved as external modules. This simplifies the development of complicated cal- 
culations for high-energy physics in large collaborations. This desktop program is 
open-source licensed and is available on the LINUX and Windows/Cygwin plat- 
forms. 
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1 Tabular Summary 



Program name: 
Version: 

Date of last version: 

Author: 

Size: 

Operating system: 
Additional packages needed: 
Program requirements: 
Programming language: 
User manuals: 
RMC files : 
Program availability: 



RunMC 
3.3 

February, 2005 
Sergei Chekanov 

15M (Linux/Windows-Cygwin), 12M (Windows- Cygwin) 

Linux, Windows/Cygwin 

CLHEP, ROOT, CERNLIB with PDFLIB 

g77, g-|--|-, make, Xll, Java JRE1.4 and higher 

C++, C, Fortran, Java, bash 

integrated into RunMC GUI 

integrated into RunMC GUI 

http : / / www . desy . de/ ~ chekanov/ runmc/] 



http : / / www . hep . anl . gov/ chakanau/ runmc /| 



2 Introduction 



General-purpose Monte Carlo (MC) models for high-energy collisions of ele- 
mentary particles are important tools used by theorists and experimentalists 
in their research. At present, the MC models written in FORTRAN are widely 
used in many high-energy physics laboratories worldwide (CERN, HERA, Fer- 
milab etc.). These models are known to be fast, robust and well tested. 

However, the main choice for future high-energy experiments is an object- 
oriented programming language, either C++ (the LHC experiments at CERN) 
or Java (the NLC project). Recently, a few steps towards converting the FOR- 
TRAN MC models to the C++ programming language were already under- 
taken [1,2]. Such rewriting can take some time, since complicated physics 
codes written in the old-fashion FORTRAN cannot be easily converted to the 
modern object-oriented programming language. Furthermore, the MC models 
written in C++ require a thoughtful verification to insure that their predic- 
tions are consistent with the original FORTRAN-based MC programs, as well 
as with the physics results obtained in the past. Such verifications will go over 
certain time, and a tool which allows to perform such comparisons is urgently 
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needed. 



Clearly, a program which allows running of both FORTRAN-coded and C++ 
MC models using a common C++ programming environment should be valu- 
able. This is important not only for comparisons and verifications of these 
MC models. Such C++ framework can also extend the lifetime of FORTRAN- 
based models especially for the LHC, NLC and TEVATRON communities, and 
can provide compatibility of most popular MC models with the new software 
to be used in the future. In this approach, the MC output should be converted 
to C++ classes for further analysis or graphical representation (histograms). 

The RunMC package provides this possibility. In addition, the graphical user 
interface (GUI) of this package was designed to be as user friendly as possible. 
It helps to initialise the MC models and the user calculations, as well as to 
monitor the event generation. It also provides a significant flexibility to fill his- 
tograms and, at the same time, different MC models can be generated without 
changing the user code and histogram settings. In future, Monte Carlo mod- 
els based on C++ can also be included. Thus, RunMC will provide a unified 
approach to generate and analysis very different MC models independent of 
their native codes. 

The RunMC program fully complies with the change in the programming 
paradigm of data analysis. Instead of the FORTRAN-based analysis tools, 
such as PAW [3] and HBOOK [4], it uses the modern CERN C++ analysis 
packages, CLHEP [5,6] and ROOT [7,8]. Therefore, the program meets the 
requirements of future high-energy experiments. 

In this respect, the RunMC program is similar to the Jet Web server [9], which 
also provides the ability to compare the existing MC models and to confirm 
the physics assumptions they contain. However, in contrast to Jet Web, the 
RunMC program was designed as a standalone desktop application. Therefore, 
the user has full access to his calculations and to the program itself. 

The RunMC package is not only the common C++ frond-end of Monte Carlo 
models designed to work with the modern analysis and graphic environment. 
Within this approach, the concept of project modules was introduced. A 
project file, which can contain external calculations, MC tunings, histogram 
definitions, etc. can be loaded to RunMC with the same ease as a document 
can be opened in the Microsoft Word program. Due to such simplicity, the pro- 
gram can be used for educational purposes, since very different aspects of the 
hadronic final states can easily be studied in a few mouse clicks. The project 
files are small and platform independent, therefore, it is fairly simple to share 
complicated physics calculations between scientists in large collaborations. 
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Fig. 1. The diagram shows the structure of the RunMC program. 
3 The structure of RunMC 



The RunMC package consists of the two parts: RunMC GUI and RunMC 
MC programs. There are two implementations of RunMC GUI: one is written 
using the Wide Studio C++ classes [10], and an alternative GUI based on 
Java. 

The RunMC MC programs are based on the ROOT and CLHEP packages 
integrated with the FORTRAN MC models. A schematic structure of RunMC 
is illustrated in Fig. 1. 

At present, the following MC models are included: PYTHIA 6.2 [11], HER- 
WIG 6.5 [12], ARIADNE 4.12 [13], LEPTO 6.5 [14], AROMA 2.2 [15], CAS- 
CADE 1.2 [16], PHOJET 1.05 [17], RAPGAP 3.1 [18]. Thus, there are several 
executable RunMC MC programs corresponding to each such MC model. 

It should be pointed out that many hard processes included in such models 
come from other authors. In future certain physics algorithms can be replaced, 
and new processes can be added [19]. The RunMC package should reflect such 
a modularisation as much as possible. Therefore, an attempt will be made to 
accommodate this trend. 

RunMC GUI communicates with the RunMC MC programs using pipe flies 
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located in a directory called "$RUNMC/pipes" . Here, "$RUNMC" denotes 
the installation directory of the RunMC project. All the directories to be 
discussed below are assumed to be located in this directory. 

The RunMC MC programs and RunMC GUI can be installed and run inde- 
pendently of each other. These programs are located in the "bin" directory. 



3.1 RunMC GUI 

RunMC GUI allows an interaction between the user and RunMC MC pro- 
grams. At present, two types of RunMC GUI are available: a user interface 
based on C-I--I- (can be executed with the command "runmc") and that based 
on Java (the command "jrunmc"). After the RunMC installation, the Java 
archive file "JRunMC.jar" , which is called by the "jrunmc" bash script, is 
located in the "bin" directory. Below we will describe the C-|— I- RunMC GUI 
only since the Java-based GUI is very similar. 

The task of RunMC GUI is to generate the output file "project.mc" , where 
"project" is a user-defined name of the current calculation. This file contains 
the most important information for the physics analysis: 

• the type of MC model, the number of events to generate, the type of the 
initial particles, their energy and the structure functions. It also specifies 
the type of the output final state (partons, stable hadrons, charged hadrons, 

hadronic jets); 

• the type of the output file: ROOT histograms or ROOT event trees. Two 
types of the ROOT trees can be filled: the complete HEPEVT event record 
or only the final states selected via RunMC GUI (i.e. partons, stable hadrons 
etc.). The latter event record, which is called the RunMC ROOT tree, con- 
tains the most important variables which are sufficient to do most physics 
studies (jet reconstruction, event shapes, inclusive particle spectra etc.). 
The size of the RunMC event record is typically four times smaller than the 
HEPEVT record; 

• the kinematic cuts applied for events or final particles/jets. The cuts can 
be set on the transverse energy and/or pscudorapidity of selected particles 
(or jets). In case of deep inelastic scattering, the range in Q^, x, y and W 
kinematic variables can be set; 

• the presentation styles of histograms and the size of the ROOT canvas. The 
histograms can be filled without normalisations or they can be normalised to 
the total number of generated events. Also, differential cross sections can be 
calculated taking into account the predicted luminosity and the histogram 
bin width (this option is supported for one- dimensional histograms only); 

• the pipe files used to communicate with the RunMC MC programs; 
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• the histogram definitions (the titles, the number of bins, the minimum and 
the maximum values, histogram dimensions). 

RunMC GUI adopts the following strategy to define the histograms: There are 
two GUI windows, "Variables" and "Histograms" . The first window contains 
the names of the variables (with some additional comments) defined for a given 
physics project. The user should select the appropriate variable and copy it 
to the "Histograms" window by clicking on the corresponding title or icon. 

The variable names are divided into the three categories: event-based variables 
(characterising the event as whole), single-particle densities (filled for each 
particle/jet; the variable name starts with "@") and two-particle densities 
(filled for each particle/jet pair; the name starts with "@@"). Such naming 
convention is necessary to avoid unnecessary loops over particles or particle 
pairs if single or two-particle densities are not required by the user. 

The histograms can also be filled in the user-defined subroutine "user-run. cpp" ; 
in this case the naming convention for the variables discussed above is unnec- 
essary. 

Two-dimensional histograms can also be filled. If two one- dimensional his- 
tograms are defined, a two-dimensional histogram can be build from these 
two histograms using RunMC GUI. 

To start the MC run, the command "runmc" should be executed from the 
project directory "proj" (or "jrunmc" if the user prefers the Java GUI). 
RunMC GUI allows the selection of the MC models, the initial particles, 
their energies, the number of events, the output required, the project name. 
The histograms can be defined by clicking on the "Variable" list and using a 
spreadsheet-like window "Histograms" . The MC run can be started by execut- 
ing the command " Start" . If specific MC settings are required, rather than the 
default parameters, one can create a steering file (with the extension ".cards") 
to change initial MC parameters. This can be done using a spreadsheet-like 
editor of RunMC GUI. Next, the program performs some basic checks, and in 
case of problems, reports them. If no errors are found, RunMC GUI performs 
the following actions: 

• creates a file called "project. mc", where "project" is the name given by the 
user. This file contains the settings described above. It is always linked to 
".analmc.ln" which will be read by the RunMC MC program; 

• creates a file called "MCname.cards" , where "MCname" is the name of 
the current MC model ( "pythia6" , "herwig" , "ariadne" , "lepto" , "aroma" 
"cascade"). This steering file contains initial parameters of the MC models. 
Note that such file may not be needed if the default MC parameters are 
required; 

• creates a pipe file called "XX.stop", where "XX" is a unique number as- 
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signed by RunMC for the current run. This file, located in the directory 
"pipes", contains zero if the MC run is allowed or "1" if the current run 
should be terminated; 

• creates a pipe file called "XX.event" . This file, filled by the RunMC MC 
programs during the MC run, contains the number of generated MC events. 
This number will be read by RunMC GUI to display the current status. 

• executes one RunMC MC program corresponding to the selected MC model. 
The executable file has the name "analmc.MCname" , where "MCname" is 
the name of MC model. 

During the event generation, the ROOT canvas can display the output his- 
tograms (up to eight in total), as well as how many events have been generated. 
The output from RunMC MC is written to ".analmc.log" (a symbolic link to 
the "project.log" file). One can view the log file using the "log" option of 
RunMC GUL At the end of the run. an additional window can appear with 
the run information (the name of MC model, the number of the MC events 
processed, the luminosity used etc.). Possible errors arc redirected to the file 
"project. err" , which is constantly monitored by RunMC GUI. 

The ROOT histograms are automatically modified at the end of the fill if they 
are required to be normalised to the total number of events or converted to 
differential cross sections. Note that there is no need to wait until the end of 
the current run: once the histogram statistics is sufficient, one can terminate 
the run by chcking "Stop" on the GUI window. Histograms should be saved in 
the ROOT file "project. root" for further studies. The style of the histograms 
can further be modified using the ROOT canvas editor. 

All user manuals for the MC models and the RunMC user manual can be 
accessed via RunMC GUI using the "Help" option. 

3.2 The RunMC MC programs 

The RunMC MC programs, which are based on the FORTRAN Monte Carlo 
models and ROOT, have the genetic name "analmc.MCname", where "MC- 
name" is the name of the corresponding MC model. The main function in the 
file "analmc.cpp" , which is located in the directory "main/src" , calls the FOR- 
TRAN subroutine "runmcarlo" to be described below. This main program is 
based on C++ and ROOT. The C++ code accesses the HEPEVT common 
block of a given MC program via a C-like structure. The RunMC MC pro- 
gram receives the initial parameters set by RunMC GUI via the symbohc fink 
".analmc.ln" pointing to the file "project. mc". 

Each MC model has its own FORTRAN subroutine "runmcarlo", which pro- 
vides an interface to the FORTRAN code of the given MC program. This in- 
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terface program (in the file "RUNMC-MCnamc.f") is located in the directory 
"main/mcarlo/MCname" . The task of the subroutine "runmcarlo" is to fill the 
HEPEVT common block. In addition, some initial settings are done by access- 
ing a C/C++ structure with the initial parameters defined in the "project. mc" 
file. The main function in "analmc.cpp" calls this interface subroutine and fills 
the C/C-I-+ structure which represents the complete HEPEVT event record. 
Next, this structure was used to select the final state generated by the MC 
models. The output is copied to the class "HEPLIST" which can be accessed 
by external calculations. The class HEPLIST consists of several vectors based 
on the LorentzVector vector class (from the CLHEP hbrary) which represents 
four- momentum of a particle or a jet. The definition of the HEPLIST class, 
as well as other include files, can be found in the "main/inc" directory. 

In addition to the FORTRAN subroutine "RUNMC-MCname.f" , which com- 
municates with the MC programs, the directory "main/mcarlo/MCname" con- 
tains an additional FORTRAN subroutine in "RUNMC-MCname-stccr.f" . It 
was designed to read the initialisation file ( "MCname.cards" ) located in the 
user directory "proj". 

The main function tries to determine which loop is necessary to use to fill the 
histograms. This decision is based on the naming convention for the RunMC 
variables described in Section 3.1. Note that the RunMC MC programs do not 
require recompilations, since the histograms are set via the input file. For a 
larger flexibility, the histograms can also be flUed manually in the user-defined 
file "user-run. cpp" (see Section 4). 

A several physics packages are available inside RunMC MC to transform the 
original four-momentum vector of particles/jets to the required observable: 

• the transformations provided by the physics vector class "LorentzVector" 
from CLHEP can be used, since a particle or a jet is represented as a general 

four-vector based on this class; 

• the event-shape calculations are available using the package developed by 
M. Iwasaki [20]; 

• the longitudinally-invariant kx algorithm as implemented in C-|— I- [21] can 
be used for the jet reconstruction. In addition to this package, the JADE 
and Durham jet algorithms are implemented according to M. Iwasaki [20]; 

• the Breit frame was implemented for ep deep inelastic scattering. 

The physics packages with the corresponding documentation are located in 
the directory "main/physics". 

The transformations based on the LorentzVector class belong to a high-level 
layer of the RunMC event record. The user still can access more elementary 
event records which can be used to transform them to other event classes and 
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physics calculations'*^ . For example, the FORTRAN HEPEVT common block 
can directly be accessed using a C++ structure inside the RunMC package. 



4 User calculations 

For a new physics calculation, the directory "proj" should be modified. This 
user directory can contain external calculations, steering cards for MC ini- 
tialisations, as well as the standard RunMC functions which are necessary to 
initialise and fill the histograms. 

The user directory should always contain the file "project. mc" created by 
RunMC GUI. This file can be edited manually without the RunMC GUI 
program using any text editor. One can load this file to RunMC GUI by 
executing the command "runmc project. mc" from the bash shell (or using the 
option "Projects^read MC" of RunMC GUI). This updates the RunMC GUI 
program according to new project settings. 

The directory "proj" can contain steering files "MCname. cards" to redefine ini- 
tial MC parameters. Such files can be created via RunMC GUI ("MC settings" 
option). For more fiexibility, the MC initialisation parameters can also be over- 
written by FORTRAN-coded subroutines located in the directory "proj/ini". 
If this is not done, the default MC parameters will be selected according to 
the RunMC option. 

The histograms can be defined in the two steps: First, a necessary variable 
should be calculated in the file "user_afill.cpp" . The output of this function 
is a pointer. The output variable name should always be associated with this 
pointer. As was explained above, three types of the variables can be defined 
(for each event, for each particle/jct, for each particle/jet pairs). Next, the 
variable names should be specified in the file "user-name. txt". It includes the 
variable names to the list "Variables" accessed by RunMC GUI. Finally, to 
compile the source codes in the directory "proj" and to rebuild all RunMC 
MC programs to take into account changes made in the project source files, 
one should type "make" in the "proj" directory. All MC programs will be 
recompiled and RunMC GUI will be updated with new histograms. Then, the 
"runmc" command should be executed in the user directory to start RunMC 
GUI. The main advantage of this approach is that once a necessary variable 
is defined, new histogram definitions do not require the recompilation of all 
MC models. 



This can be done in the user directory "proj", and packed in a physics-project 
module, see Sections 4 and 5. 
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However, the approach discussed above has some hmitations since more com- 
phcated observables cannot be filled (for example, if they are constructed 
from three or more particle densities). Therefore, to avoid this restriction, 
the RunMC histograms can also be filled using the conventional method, i.e. 
in the function located in "user-run. cpp" . In this case, the initialisation of 
histograms is not required, as long as the file "project. mc" defines which his- 
tograms should be filled and what presentation style should be used to fill the 
histograms. 

To have even more fiexibility, the histograms can be initialised in the file 
"user- init. cpp" according to the standard ROOT procedure. In this case, each 
redefinition of the histograms (the bin size, the title etc.) requires recompila- 
tion of all RunMC MC programs, i.e. it is necessary to run "make" from the 
"proj" directory. 

All RunMC MC histograms and the ROOT canvas can be accessed by the 
user using the C/C-I--I- "extern" statement. 



5 Physics projects 

In order to share complicated analysis calculations and store them for further 
use in a future, the directory "proj" can be packed into an external file. Such 
a file, which contains the zipped directory "proj", is called the RMC project 
file. It has the extention "rmc" . For example, "project. rmc" is the RMC file 
which has a user-defined name "project" . The "proj" directory inside of this 
RMC file has one and only one file "project.mc" with RunMC GUI settings. 
As was discussed in Section 4, this directory may contain some user-defined 
external functions, libraries, make files and MC steering files. 

RunMC GUI can read such project RMC file automatically using the option. 
"Projects— >load RMC" . The RunMC GUI program does this in a few steps: 

• unzips this file and replaces the content of the directory "proj" with new 
files from "project.rmc" . The old user directory is zipped and copied to the 
directory "main/tmp"; 

• recompiles the project (i.e. it executes "make" from the directory "proj"). 
RunMC GUI displays the status bar indicating the compilation process; 

• updates the GUI window with new variables, histograms and options. 

After a short time (typically 30-60 sec depending on the CPU), the new project 
is loaded to RunMC GUI. To run it, the user should select "Start ^Run", 
and after making sure that the project can successfully be executed, make 
necessary modifications via RunMC GUI or in the source files. 
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To save the project, one should select "Projects— >archive RMC". This creates 
the file "project. rmc" from the content of the directory "proj". Then this file 
will be copied to the directory "archive" . 

At present, several RunMC project files are available on the Web [22] (they 
are also included in the directory "archive" of RunMC) : 

• the default project. Only pre-installed variables can be included in the cal- 
culations. All user-defined functions in the directory "proj" are dummy; 

• HERA kinematic variables calculated in user-defined functions (Q^, x etc.); 

• jets at HERA using the longitudinally-invariant algorithm in the Breit 
frame; 

• jets at LHC. As for the previous module, the jet cross sections are recon- 
structed using the longitudinally-invariant kr algorithm; 

• jet cross sections at LHC for parton and hadron levels. This project contains 
the calculation of hadronisation corrections by taking the ratio of these cross 
sections. It also illustrates how to initialise and to fill histograms in the 
function "user-run. cpp" ; 

• calculations of the D* cross sections in ep collisions at HERA; 

• calculations of the cross sections for strange-particle production in ep colli- 
sions at HERA; 

• the HZTOOL package [23]; 

• the event-shape variables in e^e~ at NLC energies; 

• several examples of how to visualise tracks and the kr jets in 3D for a 
single MC event (e"'"e~, ep, pp collisions). They use a simple imitation of 
the magnetic field using the example taken from the ROOT project [7,8]. 

The RMC project files discussed above only illustrate how to set up and 
to develop new physics calculations in the RunMC framework. For practical 
applications, these examples should be modified. 



6 Running in the background 

Due to a complete independence of RunMC GUI and RunMC MC programs, 
one can run jobs in the background without GUI or any pop-up window. This 
can be done using the following steps: 

• edit the source files in the directory "proj" , or unzip a RMC project file to 
this directory. Recompile the project by typing "make" from the directory 

"proj"; 

• make sure that the file "project. mc" is linked to ".analmc.ln" . If you do not 
want ROOT pop-up canvas with histograms, a corresponding option should 
be set in the file "project.mc" (see the fine "OPTIONS" in "project.mc". 
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you may use RunMC GUI first to find out which RunMC parameter should 

be modified); 

• execute the file "analmc.MCname" corresponding to the particular MC 
model. Normally, the program should ask first to create a pipe file with 
"0" in the directory "pipes" which allows this run. 

The MC run can be terminated at any time by setting "1" in the pipe file. All 
histograms should be saved in the file "project.root". 



7 RunMC ROOT tree analyser 



In addition to the standard functionality of the MC event simulation, RunMC 
GUI can also use ROOT trees as the input for physics calculations. 

The ROOT tree can be generated by selecting an appropriate option via 
RunMC GUI, either "HEPEVT" or "RUNMC", in addition or instead of 
the ROOT histogram option. Then, the MC events should be generated as 
usual, but this time a ROOT tree with the extention ".rtup" or ".htup" will 
be created. Then, RunMC can run over this ROOT tree if, instead of the MC 
model, the option "RUNMC" or 'HEPEVT" is selected. Several ROOT trees 
can automatically be included in the analysis as long as they are of the same 
type and located in the same directory. 

The analysis of the ROOT trees is very similar to the standard run over MC 
events. The external RMC files can be used to define new variables and to 
specify the output histograms. The only difference is that the cross section 
calculations are not possible at present. 

The main advantage of the ROOT tree analyser is that physics calculations 
and histograms can be produced significantly faster than when MC models 
are used to generate and to fill histograms at the same time. In case of the 
ROOT tree, RunMC can fill histograms by a factor ~10-15 faster, thus the 
RMC project files can be vahdated and analysed more efficiently. 

With this additional feature, RunMC can also be used to analyse experimental 
data if the event record is converted to the appropriate ROOT tree. As for 
the Monte Carlo models, the data analysis can be performed using the RMC 
project files. 
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